home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / pcxkit.exe / CLIP.DOC < prev    next >
Text File  |  1992-01-11  |  17KB  |  370 lines
  1. ===========================================================================
  2.  
  3.                                     CLIP
  4.  
  5.                              by Peter Donnelly
  6.                               1301 Ryan Street
  7.                                 Victoria BC
  8.                                Canada V8T 4Y8
  9.  
  10. ===========================================================================
  11.  
  12. INTRODUCTION
  13. ------------
  14.  
  15. The Borland Graphical Interface contains an easy-to-use procedure,
  16. PutImage, for displaying complex images on a portion of the screen.
  17. However, the Turbo C or Pascal programmer faces the difficulty of getting
  18. the image into a usable form in the first place - that is, of drawing it 
  19. and then converting it into the format that PutImage requires.
  20.  
  21. CLIP is a bridge between powerful commercial painting programs and the BGI. 
  22. It lets you "clip" images of any size (up to the 64K limit imposed by 
  23. PutImage) from PCX files in EGA and VGA medium or high resolution, and puts 
  24. these images in files that can be used in your C or Pascal routines with a 
  25. minimum of effort.
  26.  
  27.  
  28. OPERATION
  29. ---------
  30.  
  31. The program is very simple to use. First create a screen-wide PCX graphics 
  32. file in 16-color 640x200, 640x350, or 640x480 resolution, using a painting 
  33. or screen-capture program. (If your software doesn't directly support the 
  34. PCX format, it may include a conversion program that does.) Then run CLIP 
  35. with the pathname of the graphics file on the command line; don't include 
  36. the ".PCX" part.
  37.  
  38. By default the program will come up in 640x480 resolution if your system
  39. supports it, but you can override this default by entering "/e" on the
  40. command line after the PCX file name, in which case the display mode will
  41. be 640x350 and only EGA palette information will be produced (more on this
  42. below).
  43.  
  44. Now, with the mouse, point to one corner of the image you wish to save.
  45. Hold down the left button and drag the mouse to create a frame around the
  46. image. The area you are defining includes the pixels covered by the frame
  47. lines, so that you can work right to the edge of the screen.
  48.  
  49. When you release the button, you are prompted to enter a name for the image
  50. file. Type the file name and press <Enter>, or abort with <Esc>. You may
  51. use any file name except one with the extension ".PAL".
  52.  
  53. If the image is too large for the BGI PutImage procedure, a bell sounds and
  54. you are not allowed to save. The size limit is about 58 percent of the
  55. screen in EGA mode or about 42 percent in VGA. If you want to save the
  56. entire screen, you can of course do so in chunks; but a better way is to
  57. use PCX.PAS to display the original PCX image in your program.
  58.  
  59. By default the co-ordinates of the mouse are shown at the upper right
  60. corner of the screen. This information can be useful for cutting images
  61. exactly to size, especially if you have made a note of the desired
  62. boundaries while working in the magnified mode of your painting program.
  63. CLIP will ignore the display of co-ordinates when saving an image clipped
  64. from this part of the screen; however, you can toggle off the display with
  65. <F1> if you wish to see what lies beneath.
  66.  
  67. Continue saving images from the screen until you're done; then press
  68. <Alt-X> or <F10> to exit.
  69.  
  70.  
  71. USING CLIP IMAGES IN TURBO PASCAL AND TURBO C
  72. ---------------------------------------------
  73.  
  74. The data structure used by Borland's image-manipulating procedures and
  75. functions is the same in both Turbo Pascal and Turbo C, and CLIP's
  76. output files are equally usable with either language. The examples in this
  77. section will be in Pascal.
  78.  
  79. The disk file created by CLIP to store an image takes exactly the same
  80. form as the data structure created by the Turbo GetImage procedure and used
  81. by PutImage. It is an untyped file.
  82.  
  83. The first two words in the file store the width and height respectively of
  84. the image (counting from zero: an image of "1 by 1" is actually 2 by 2).
  85. The PutImage procedure uses these figures to set up the image properly, and
  86. they are also used by ImageSize to calculate the storage needed for the
  87. image. The BGI does not use data compression; a blank image occupies as
  88. much storage space as a complex image of the same dimensions.
  89.  
  90. Here is a simple routine to import an image from a file and display it at
  91. the current pointer.
  92.  
  93.   var    BitMap: Pointer;
  94.          f: file;
  95.  
  96.   Begin
  97.     Assign(f, 'MYIMAGE.IM');
  98.     Reset(f, 1);
  99.     GetMem(BitMap, FileSize(f));
  100.     BlockRead(f, BitMap^, FileSize(f));
  101.     PutImage(GetX, GetY, BitMap^, CopyPut);
  102.   End;
  103.  
  104. For a program that uses multiple images, it may be convenient to group all
  105. the images together in a single data file. It is easy to do so with the DOS
  106. Copy command. For example, to create a file "CHESSMEN" containing all the
  107. pieces:
  108.  
  109.   COPY KING/B + QUEEN + BISHOP + KNIGHT + ROOK + PAWN CHESSMEN
  110.  
  111. Note the "/B" argument after the first filename. Do not omit this; it is
  112. essential so that DOS treats all the files as binary and does not truncate
  113. any on encountering a Control-Z.
  114.  
  115. Obviously it is up to the programmer to ensure that the file-reading
  116. routines take into account the number of bytes occupied by each image. If
  117. the file contains images of different sizes that are to be stored
  118. dynamically as they are imported, you can use the ImageSize function to
  119. determine how much memory to allocate for each image:
  120.  
  121.   var   Width, Height, Size: word;
  122.         BitMap: pointer;
  123.         f: file;
  124.  
  125.   Begin
  126.     Assign(f, 'IMAGES.DTA');
  127.     Reset(f, 1);
  128.     Repeat
  129.       BlockRead(f, Width, 2);               { Get dimensions from header }
  130.       BlockRead(f, Height, 2);
  131.       Size:= ImageSize(0, 0, Width, Height);
  132.       GetMem(BitMap, Size);
  133.       Seek(f, FilePos(f) - 4);              { Back up }
  134.       BlockRead(f, Bitmap^, Size);          { Get whole image }
  135.     Until Eof(f);
  136.   End;    
  137.  
  138. This routine has the great advantage that you can alter the size of any of
  139. the component images in the file without having to change program code.
  140.  
  141.  
  142. INCORPORATING PALETTE CHANGES
  143. -----------------------------
  144.  
  145. Whenever you save an image file, CLIP automatically creates a palette
  146. file with the same name and the extension ".PAL". If CLIP is running in
  147. EGA (350-line) mode, this is simply an untyped 17-byte file containing a
  148. PaletteType record. For the VGA, it is an array of the RGB values for each
  149. of the 16 palette entries, or 48 bytes in all.
  150.  
  151. If you are working in 350-line mode on the VGA, the program presumes that
  152. you want only EGA palette data. If you want the full VGA information, you
  153. can load the file in 480-line mode; the resulting distortion will make no
  154. difference if the clipped images are ultimately to be displayed in their
  155. original 350-line format.
  156.  
  157. For the EGA, you can easily import saved palette values into your own
  158. program by BlockReading the palette file into a PaletteType variable. It is
  159. then simply a matter of passing that variable into SetAllPalette. (Of
  160. course, in many cases it may be preferable to hard-code the palette values,
  161. which can be examined with DEBUG.)
  162.  
  163. For the VGA, things are a bit more complicated. Here you have to make these
  164. declarations:
  165.  
  166.    type    RGBrec = record
  167.                       redval, greenval, blueval: byte;
  168.                     end;
  169.  
  170.    var     RGBpalette: array[0..15] of RGBrec;
  171.  
  172. Now BlockRead the palette file into RGBpalette. From here the data can be
  173. passed into Turbo's SetRGBPalette procedure; but first you have to make
  174. sure that the palette entries are pointing to the registers you are
  175. modifying. (In the VGA, the 16 palette entries don't contain color values;
  176. they contain the numbers of color registers, which in turn hold the actual
  177. colors.) By default the palette points to registers 0-5, 20, 7, and 56-63,
  178. which contain the standard EGA colors. You can either modify these
  179. registers or else use SetPalette to put the numbers 0-15 in the palette,
  180. then modify registers 0-15 with SetRGBPalette.
  181.  
  182. Files of 640x200 resolution are a special case. If you want to display
  183. images in the BGI "EGALo" format, only the 16 default colors are available,
  184. so it is unlikely you w